ODTransform

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODTransform

Superclasses
ODRefCntObject --> ODObject
Subclasses
none

An object of the ODTransform class maps points and shapes from one coordinate system to another. This can be viewed as modifying a shape, for example, by scaling or rotating it.

Description
A transform uses a 3-by-3 matrix to perform two-dimensional transformations. The simplest transform is an identity transform, which has no effect on any points or shapes that it transforms.
Your part creates a new identity transform by calling the CreateTransform method (page 316) of a frame, the CreateTransform method (page 241) of a facet, or the NewTransform method (page 778) of an existing transform. Your part can create a copy of an existing transform by calling that transform's Copy method (page 766).
You can use a transform to perform the following transformations on coordinates or shapes:

Translation (offset) shifts the position of a shape.
Scaling changes the size of a shape.
Rotation changes the angle of rotation of a shape, rotating all points around a given point.
Skewing changes the slant applied to a shape.
Perspective modifies the positions of points to give a three-dimensional effect.

For more information on matrices and transformations in two-dimensional drawing, you can consult any standard computer-graphics textbook, such as Computer Graphics Principles and Practice, second edition, by Foley, vanDam, Feiner, and Hughes (Addison-Wesley, 1990). You can also refer to the chapter on drawing in the OpenDoc Programmer's Guide for the MacOS.
You do not need to subclass ODTransform. However, you can provide for new transforms by creating subclasses of ODTransform. For example, you can define new transforms that do not use transformation matrices. These new transforms might perform more complex operations, such as morphing or wrapping around a 3D surface.

Overriding Inherited Methods
The following methods are inherited and available for use by your subclass of ODTransform.

somInit
The somInit method initializes the instance variables in a SOM object; it is inherited from the SOMObject class.
If you subclass ODTransform, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should initialize the new instance variables in this transform object. The SOM library calls this method when this transform object is created. You must not do anything that might fail in this method. This limits you to operations such as setting pointer variables to null, setting numeric variables to appropriate values, and making similar assignments from constants. If you have any initialization code that can potentially fail, it must be handled in this transform object's subclass-specific initialization method; see also the InitTransform method (page 773).

somUninit
The somUninit method disposes of the storage created for a SOM object; it is inherited from the SOMObject class.
If you subclass ODTransform, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should dispose of any storage created for this transform object, including any storage related to additional instance variables initialized in this transform object. The SOM library calls this method when this transform object is deleted; this method must not fail.

Purge
The Purge method frees memory on request; it is inherited from the ODObject class.

ODSize Purge (in ODSize size);
Every subclass of ODObject can override this method and should do so if it creates caches and temporary buffers. If you subclass ODTransform, you must override this method or risk running out of available memory. Your override of this method must call its inherited method at some point in your implementation (it does not matter where). You should save the size value returned by the inherited method because you will need it to compute the value to return from your override method.
Your override of this method should free any caches, noncritical buffers, or objects (up to the amount of memory specified). Your override of this method should add the number of bytes actually freed to the number returned by the inherited method and return the sum as the total amount of memory released. OpenDoc calls this method in low-memory situations; you should not allocate memory for this operation.

Methods
This section presents summary descriptions of the ODTransform methods grouped according to purpose, followed by detailed descriptions in alphabetical order. Methods marked [M] are specific to the Mac OS platform.
Creating Transforms

NewTransform
Creates a new identity transform.
Copy
Creates a new transform that is a copy of this transform.
Applying the Transform

TransformShape
Modifies the specified shape by applying this transform.
InvertShape
Modifies the specified shape by applying the inverse of this transform.
TransformPoint
Modifies the location of the specified point by applying this transform.
InvertPoint
Modifies the location of the specified point by applying the inverse of this transform's matrix.
Testing the Transform

GetType
Returns the transform type of this transform.
IsSameAs
Returns a Boolean value that indicates whether this transform is identical to the specified transform.
HasMatrix
Returns a Boolean value that indicates whether this transform uses a matrix to describe its transformation.
Manipulating the Matrix

ReadFrom
Reads this transform's matrix from the specified storage unit.
WriteTo
Writes this transform's matrix to the specified storage unit.
GetMatrix
Copies this transform's matrix into the specified structure.
SetMatrix
Replaces this transform's matrix with the specified matrix.
PostCompose
Modifies this transform's matrix by postmultiplying it with the specified transform's matrix.
PreCompose
Modifies this transform's matrix by premultiplying it with the specified transform's matrix.
CopyFrom
Modifies this transform to make it equivalent to the specified source transform.
Invert
Inverts this transform's matrix.
Reset
Changes this transform to an identity transform.
Manipulating the Translation Values

GetOffset
Returns this transform's translation values (also called offset values) in the specified structure.
SetOffset
Changes this transform into a pure offset with the specified horizontal and vertical translation values.
GetPreScaleOffset
Returns, in the specified structure, the offset to use if you are going to apply the offset before scaling.
MoveBy
Offsets this transform's horizontal and vertical translation values by the specified amount.
IsQDOffset [M]
Returns a Boolean value that indicates whether this transform is a pure offset with integral translation values.
GetQDOffset [M]
Returns this transform's offset value expressed as a QuickDraw point.
SetQDOffset [M]
Changes this transform into a pure offset with the specified integral horizontal and vertical translation values.
Manipulating the Scaling Factors

GetScale
Returns this transform's horizontal and vertical scaling factors in the specified structure.
ScaleBy
Scales this transform by the specified vertical and horizontal scaling factors.
ScaleDownBy
Scales this transform by the reciprocal of the specified vertical and horizontal scaling factors.
Initializing

InitTransform
Initializes this transform. This method is needed only if you subclass ODTransform.

Methods
Copy
CopyFrom
GetMatrix
GetOffset
GetPreScaleOffset
GetQDOffset
GetScale
GetType
HasMatrix
InitTransform
Invert
InvertPoint
InvertShape
IsQDOffset
IsSameAs
MoveBy
NewTransform
PostCompose
PreCompose
ReadFrom
Reset
ScaleBy
ScaleDownBy
SetMatrix
SetOffset
SetQDOffset
TransformPoint
TransformShape
WriteTo